OAuth Integration & Credentials Guide
This guide provides instructions for setting up OAuth applications and managing credentials for Atom's 45+ native integrations.
1. Universal Callback URLs
When setting up your OAuth applications (Slack, Google, Salesforce, etc.), you must configure the **Redirect URI** to point to your Atom instance.
| Handler Type | Primary Callback URL | Use Case |
|---|---|---|
| **Native (Unified)** | https://app.atomagentos.com/api/integrations/callback | **Recommended.** Used for Salesforce, HubSpot, Slack, and common native flows. |
| **Universal (Activepieces)** | https://app.atomagentos.com/api/v1/integrations/universal/callback | Used for Activepieces-driven integrations (e.g. Gmail, Google Drive, Box). |
---
2. Setting Up Common Integrations
**Pattern A: Custom Managed Flow (Native)**
These use the **Native Callback**: https://app.atomagentos.com/api/integrations/callback
| Service | Scopes | Client ID Env | Client Secret Env |
|---|---|---|---|
| **Slack** | channels:read, chat:write, groups:read, im:read, mpim:read | SLACK_CLIENT_ID | SLACK_CLIENT_SECRET |
| **Salesforce** | api, offline_access, refresh_token, web | SALESFORCE_CLIENT_ID | SALESFORCE_CLIENT_SECRET |
| **HubSpot** | crm.objects.contacts.read, crm.objects.contacts.write, crm.objects.companies.read, crm.objects.companies.write, crm.objects.deals.read, crm.objects.deals.write, content | HUBSPOT_CLIENT_ID | HUBSPOT_CLIENT_SECRET |
| **Notion** | *(Default Scopes)* | NOTION_CLIENT_ID | NOTION_CLIENT_SECRET |
| **Zoho CRM** | ZohoCRM.modules.ALL, ZohoCRM.settings.ALL | ZOHO_CRM_CLIENT_ID | ZOHO_CRM_CLIENT_SECRET |
---
**Pattern B: Universal Integration Service (Activepieces)**
These use the **Universal Callback**: https://app.atomagentos.com/api/v1/integrations/universal/callback
**Communication & Collaboration**
| Service | Required Scopes | Env Variable Prefix |
|---|---|---|
| **Microsoft Teams** | Chat.ReadWrite, User.Read, ChannelMessage.Send | TEAMS_ |
| **Discord** | identify, bot, messages.read, guilds | DISCORD_ |
| **Google Chat** | chat.spaces.readonly, chat.messages | GOOGLE_CHAT_ |
| **Telegram** | *(Bot Token based, no callback required)* | TELEGRAM_BOT_TOKEN |
| **Zoom** | meeting:write, user:read | ZOOM_ |
| **Gmail** | https://www.googleapis.com/auth/gmail.modify | GOOGLE_ |
| **Outlook** | Mail.ReadWrite, offline_access | MICROSOFT_ |
| **Zoho Mail** | ZohoMail.messages.READ, ZohoMail.messages.CREATE | ZOHO_ |
---
**Pattern C: Meta/Facebook Apps (WhatsApp, Instagram, Meta Ads)**
Meta apps use a **dedicated callback**: https://app.atomagentos.com/api/integrations/whatsapp/callback
WhatsApp Business API Setup
> [!IMPORTANT]
> WhatsApp Business API requires **Business Verification** in Meta Business Suite before going live.
**Step 1: Create Meta App**
- Go to developers.facebook.com
- Click **My Apps** → **Create App**
- Select **Business** as app type
- Note your **App ID** and **App Secret** from Settings → Basic
**Step 2: Add WhatsApp Product**
- In your app dashboard, click **Add Product** → **WhatsApp** → **Set up**
**Step 3: Configure OAuth Settings**
- Go to **App Settings** → **Basic**
- Add **Privacy Policy URL**:
https://atomagentos.com/privacy - Add **Terms of Service URL**:
https://atomagentos.com/terms - Under **Data Deletion**, add:
https://atomagentos.com/api/meta/data-deletion - Under **Valid OAuth Redirect URIs**, add:
**Step 4: Get Embedded Signup Config ID (Optional)**
The Config ID enables the streamlined "Embedded Signup" flow where users can connect their WhatsApp Business account in a popup.
- Go to **WhatsApp** → **Embedded Signup** in your app dashboard
- Click **Create Configuration**
- Configure signup options:
- Enable/disable features users can access
- Set branding and messaging
- Click **Create** and note the **Configuration ID** (e.g.,
1234567890123456)
> [!TIP]
> The Config ID is optional. Without it, users go through the standard Facebook OAuth flow. With it, you get a more streamlined WhatsApp-specific signup experience.
**Step 5: Set Environment Variables**
# Add to Vault secrets
atom-cli secrets set \
WHATSAPP_APP_ID=your_meta_app_id \
WHATSAPP_APP_SECRET=your_meta_app_secret \
WHATSAPP_CONFIG_ID=your_embedded_signup_config_id \
WHATSAPP_REDIRECT_URI=https://app.atomagentos.com/api/integrations/whatsapp/callback**Step 6: Complete Business Verification**
- Go to business.facebook.com → **Business Settings**
- Click **Business Info** → **Start Verification**
- Submit required documents (business registration, tax ID, etc.)
- Wait 1-5 business days for approval
Meta App Environment Variables
| Variable | Description | Where to Find |
|---|---|---|
WHATSAPP_APP_ID | Meta App ID | App Dashboard → Settings → Basic |
WHATSAPP_APP_SECRET | Meta App Secret | App Dashboard → Settings → Basic |
WHATSAPP_CONFIG_ID | Embedded Signup Config ID | WhatsApp → Embedded Signup |
WHATSAPP_REDIRECT_URI | OAuth Callback URL | Set to https://app.atomagentos.com/api/integrations/whatsapp/callback |
WHATSAPP_ACCESS_TOKEN | Direct API Token (for your own business) | WhatsApp → API Setup |
WHATSAPP_PHONE_NUMBER_ID | Your Phone Number ID (for your own business) | WhatsApp → API Setup |
Meta Compliance Endpoints
These endpoints are automatically available and should be configured in Meta Developer Console:
| Purpose | URL | Where to Configure |
|---|---|---|
| **Privacy Policy** | https://atomagentos.com/privacy | App Settings → Basic |
| **Terms of Service** | https://atomagentos.com/terms | App Settings → Basic |
| **Data Deletion Callback** | https://atomagentos.com/api/meta/data-deletion | App Settings → Data Deletion |
| **Deletion Status Page** | https://atomagentos.com/api/meta/deletion-status?code=XXX | Automatically provided |
---
**Storage & Knowledge**
| Service | Required Scopes | Env Variable Prefix |
|---|---|---|
| **Google Drive** | https://www.googleapis.com/auth/drive.readonly | GOOGLE_ |
| **OneDrive** | Files.Read.All, Files.ReadWrite.All | ONEDRIVE_ |
| **Dropbox** | files.content.read, files.metadata.read | DROPBOX_ |
| **Box** | root_readwrite, manage_managed_users | BOX_ |
| **Zoho Workdrive** | WorkDrive.workspace.ALL, WorkDrive.files.ALL | ZOHO_ |
**Calendar**
| Service | Required Scopes | Env Variable Prefix |
|---|---|---|
| **Google Calendar** | https://www.googleapis.com/auth/calendar.readonly | GOOGLE_ |
| **Outlook Calendar** | Calendars.ReadWrite | MICROSOFT_ |
**Project Management**
| Service | Required Scopes | Env Variable Prefix |
|---|---|---|
| **Asana** | default | ASANA_ |
| **Jira Cloud** | read:jira-work, write:jira-work | JIRA_ |
| **Linear** | read, write | LINEAR_ |
| **Trello** | read, write | TRELLO_API_KEY |
| **monday.com** | me:read, boards:read, boards:write | MONDAY_ |
| **Zoho Projects** | ZohoProjects.projects.READ, ZohoProjects.tasks.READ | ZOHO_ |
**Finance & Billing**
| Service | Required Scopes | Env Variable Prefix |
|---|---|---|
| **QuickBooks** | com.intuit.quickbooks.accounting | QUICKBOOKS_ |
| **Xero** | accounting.transactions, accounting.contacts | XERO_ |
| **Stripe** | read_only (OAuth for Connect/Agencies) | STRIPE_ |
| **Zoho Books** | ZohoBooks.fullaccess.all | ZOHO_ |
| **Zoho Inventory** | ZohoInventory.fullaccess.all | ZOHO_ |
**Marketing & Advertising**
| Service | Required Scopes | Env Variable Prefix |
|---|---|---|
| **Mailchimp** | read_only | MAILCHIMP_ |
| **HubSpot Marketing** | content | HUBSPOT_ |
| **Meta Ads** | ads_management, ads_read | META_ |
| **Google Ads** | https://www.googleapis.com/auth/adwords | GOOGLE_ |
| **LinkedIn Ads** | r_ads, rw_ads | LINKEDIN_ |
| **Google Reviews** | https://www.googleapis.com/auth/business.manage | GOOGLE_ |
**Analytics**
| Service | Required Scopes | Env Variable Prefix |
|---|---|---|
| **Tableau** | tableau:content:read | TABLEAU_ |
| **Google Analytics** | https://www.googleapis.com/auth/analytics.readonly | GOOGLE_ |
**E-commerce**
| Service | Required Scopes | Env Variable Prefix |
|---|---|---|
| **Shopify** | read_products, read_customers, read_inventory, read_locations, read_orders, write_orders, write_fulfillments, write_draft_orders | SHOPIFY_ |
**Support & Helpdesk**
| Service | Required Scopes | Env Variable Prefix |
|---|---|---|
| **Zendesk** | read, write | ZENDESK_ |
| **Intercom** | read, write | INTERCOM_ |
| **Freshdesk** | *(API Key based)* | FRESHDESK_API_KEY |
**Engineering & DevOps**
| Service | Required Scopes | Env Variable Prefix |
|---|---|---|
| **GitHub** | repo, user, read:org | GITHUB_ |
| **GitLab** | api, read_user | GITLAB_ |
| **Figma** | file_read | FIGMA_ |
---
3. Implementation Checklist
- **Whitelist Domains**: In the provider console, always whitelist
app.atomagentos.com. - **HTTPS Required**: Most OAuth providers (Google, Slack) will **refuse** to redirect to
http://. Ensure you have SSL active (standard on ATOM Cloud). - **Cross-Reference**: Every
IDandSECRETmust be added to Vault secrets to be visible to the Python UIS backend.
> [!IMPORTANT]
> **Activepieces pieces**: For any integration not listed here (the "long tail"), Atom uses the Activepieces pieces engine. These always use the **Universal API Callback** and often require specific scopes defined in the piece's documentation.
In production, these credentials should be set as environment variables.
ATOM Cloud (Production)
atom-cli secrets set \
SLACK_CLIENT_ID=... \
SLACK_CLIENT_SECRET=... \
SALESFORCE_CLIENT_ID=... \
SALESFORCE_CLIENT_SECRET=... \
GOOGLE_CLIENT_ID=... \
GOOGLE_CLIENT_SECRET=...Local Development
Update your root .env file:
# OAuth Credentials
SLACK_CLIENT_ID=your_id
SLACK_CLIENT_SECRET=your_secret
# Use this for local redirect testing (usually with a tunnel like ngrok)
NEXT_PUBLIC_APP_URL=https://your-ngrok-url.ngrok-free.app> [!TIP]
> **State Security**: Atom automatically generates and validates a state parameter for every OAuth flow to prevent CSRF attacks. Active states are stored in the oauth_states table in your database.